Skip to main content

Defined in: src/constructs/progressive-lambda/progressive-lambda.ts:321

A progressive deployment Lambda function with integrated CloudWatch monitoring and CodeDeploy automation.

Overview​

This construct provides a production-ready Lambda function with:

  • Progressive Deployments: Uses AWS CodeDeploy for safe, automated rollouts
  • Error Monitoring: CloudWatch alarms that trigger rollbacks on failures
  • Observability: Optional dashboard widgets and X-Ray tracing
  • Security Best Practices: Latest runtime, SSL enforcement guidance, and proper IAM roles

Key Features​

Progressive Deployment​

  • Creates a Lambda alias for traffic management
  • Integrates with CodeDeploy for controlled traffic shifting
  • Supports various deployment strategies (linear, canary, blue/green)

Monitoring & Alerting​

  • CloudWatch alarm based on custom error metrics
  • Automatic rollback when error threshold is breached
  • SNS notifications for deployment events
  • Optional dashboard widgets for real-time monitoring

Security & Compliance​

  • Uses latest Node.js runtime by default (AwsSolutions-L1)
  • X-Ray tracing enabled for request tracking
  • Follows AWS Well-Architected Framework principles
  • CDK Nag compliant with documented exceptions

Usage Patterns​

Basic Usage​

const app = new codeDeploy.LambdaApplication(this, 'MyApp');
const alertTopic = new sns.Topic(this, 'Alerts');

const lambda = new ProgressiveLambda(this, 'ProcessorFunction', {
  entry: 'src/handlers/processor.ts',
  stageName: 'prod',
  application: app,
  deploymentConfig: codeDeploy.LambdaDeploymentConfig.LINEAR_10PERCENT_EVERY_1MINUTE,
  alarmEnabled: true,
  snsTopic: alertTopic,
  namespace: 'ECommerce',
  serviceName: 'OrderProcessor',
  metricSuccessName: 'ProcessedOrders',
  metricSuccessNameTitle: 'Successfully Processed Orders',
  metricErrorName: 'ProcessingErrors',
  metricErrorNameTitle: 'Order Processing Failures',
  region: 'us-east-1'
});

With Dashboard Widgets​

const lambda = new ProgressiveLambda(this, 'ProcessorFunction', {
  // ... other props
  createWidget: true  // Creates dashboard widgets
});

// Add widgets to a dashboard
const dashboard = new cloudwatch.Dashboard(this, 'MyDashboard');
dashboard.addWidgets(...lambda.widgets);

Canary Deployment​

const lambda = new ProgressiveLambda(this, 'RiskyFeature', {
  // ... other props
  deploymentConfig: codeDeploy.LambdaDeploymentConfig.CANARY_10PERCENT_5MINUTES,
  // Deploy 10% of traffic, wait 5 minutes, then proceed or rollback
});

Metrics Integration​

Your Lambda function code should publish the specified success and error metrics:

import { CloudWatch } from 'aws-sdk';
const cloudwatch = new CloudWatch();

export const handler = async (event) => {
  try {
    // Process event
    await processOrder(event);

    // Publish success metric
    await cloudwatch.putMetricData({
      Namespace: 'ECommerce',
      MetricData: [{
        MetricName: 'ProcessedOrders',
        Value: 1,
        Dimensions: [{ Name: 'service', Value: 'OrderProcessor' }]
      }]
    }).promise();
  } catch (error) {
    // Publish error metric
    await cloudwatch.putMetricData({
      Namespace: 'ECommerce',
      MetricData: [{
        MetricName: 'ProcessingErrors',
        Value: 1,
        Dimensions: [{ Name: 'service', Value: 'OrderProcessor' }]
      }]
    }).promise();
    throw error;
  }
};

Alarm Configuration​

  • Threshold: 10 errors within 1 minute triggers alarm
  • Evaluation: Single evaluation period to enable fast rollbacks
  • Missing Data: Treated as NOT_BREACHING to avoid false alarms
  • Actions: SNS notification and CodeDeploy rollback

See​

Remarks​

Security Considerations:

  • Uses latest Node.js runtime by default (AwsSolutions-L1 compliance)
  • Requires user-provided SNS topic to enforce SSL policies (AwsSolutions-SNS3)
  • Uses AWS managed policies for Lambda execution (AwsSolutions-IAM4 - acceptable for standard roles)
  • X-Ray tracing requires wildcard IAM permissions (AwsSolutions-IAM5 - acceptable for tracing)

Extends​

  • Construct

Constructors​

Constructor​

new ProgressiveLambda(scope, id, props): ProgressiveLambda

Defined in: src/constructs/progressive-lambda/progressive-lambda.ts:406

Creates a new ProgressiveLambda construct.

Parameters​

scope​

Construct

The construct scope

id​

string

The construct identifier

props​

ProgressiveLambdaProps

Configuration properties

Returns​

ProgressiveLambda

Throws​

When required properties are missing or invalid

Example​

const lambda = new ProgressiveLambda(this, 'MyLambda', {
  entry: 'src/handler.ts',
  stageName: 'prod',
  application: myCodeDeployApp,
  deploymentConfig: codeDeploy.LambdaDeploymentConfig.LINEAR_10PERCENT_EVERY_1MINUTE,
  alarmEnabled: true,
  snsTopic: mySnsTopic,
  namespace: 'MyApp',
  serviceName: 'MyService',
  metricSuccessName: 'Success',
  metricSuccessNameTitle: 'Successful Operations',
  metricErrorName: 'Errors',
  metricErrorNameTitle: 'Failed Operations',
  region: 'us-east-1'
});

Overrides​

Construct.constructor

Properties​

alarm​

readonly alarm: Alarm

Defined in: src/constructs/progressive-lambda/progressive-lambda.ts:344

CloudWatch alarm that monitors error metrics.

Triggers when error count exceeds threshold, causing CodeDeploy to automatically rollback the deployment to the previous version.

alias​

readonly alias: Alias

Defined in: src/constructs/progressive-lambda/progressive-lambda.ts:336

Lambda alias for traffic management during deployments.

Points to the current version and is used by CodeDeploy to shift traffic between versions during progressive deployments.

deploymentGroup​

readonly deploymentGroup: LambdaDeploymentGroup

Defined in: src/constructs/progressive-lambda/progressive-lambda.ts:352

CodeDeploy deployment group managing progressive rollouts.

Orchestrates traffic shifting between Lambda versions based on the configured deployment strategy and alarm status.

lambda​

readonly lambda: NodejsFunction

Defined in: src/constructs/progressive-lambda/progressive-lambda.ts:328

The underlying Lambda function.

Provides access to the NodejsFunction for additional configuration, permissions, or integration with other AWS services.

node​

readonly node: Node

Defined in: node_modules/.pnpm/constructs@10.0.5/node_modules/constructs/lib/construct.d.ts:305

The tree node.

Stability​

stable

Inherited from​

Construct.node

widgets​

readonly widgets: ConcreteWidget[] = []

Defined in: src/constructs/progressive-lambda/progressive-lambda.ts:364

CloudWatch dashboard widgets for monitoring (when enabled).

Contains three widgets when createWidget is true:

  1. Success metric single value widget
  2. Error metric single value widget
  3. Alarm status widget

Add to dashboards using: dashboard.addWidgets(...lambda.widgets)

Methods​

toString()​

toString(): string

Defined in: node_modules/.pnpm/constructs@10.0.5/node_modules/constructs/lib/construct.d.ts:319

Returns a string representation of this construct.

Returns​

string

Stability​

stable

Inherited from​

Construct.toString

isConstruct()​

static isConstruct(x): x is Construct

Defined in: node_modules/.pnpm/constructs@10.0.5/node_modules/constructs/lib/construct.d.ts:299

(deprecated) Checks if x is a construct.

Parameters​

x​

any

Any object.

Returns​

x is Construct

true if x is an object created from a class which extends Construct.

Deprecated​

use x instanceof Construct instead

Inherited from​

Construct.isConstruct